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1 Overview 

SpartyJet is a set of software tools for jet finding and analysis, built around 
the Fast Jet library of jet algorithms [TJ [2]. SpartyJet provides four key 
extensions to FastJet: a simple Python interface to most FastJet features, 
a powerful framework for building up modular analyses, extensive input file 
handling capabilities, and a graphical browser for viewing analysis output and 
creating new on-the-fly analyses. Many of these capabilities rely on a ROOT- 
based backend [3]. Beyond finding jets, many jet tools in SpartyJet per- 
form measurement of jet or event variables, referred to here as jet or event 
"moments" . These moments are available to subsequent tools and stored in 
the final output. SpartyJet can be downloaded from HepForge at http: 
//projects . hepf orge . org/ spartyjet 

Sec. [2] walks through a simple example. Sec. [3] gives instruction on installa- 
tion. Sec.[4]describes the overall structure of a SpartyJet run. Sec.[5]describes 
and enumerates the various jet tools available in SpartyJet. Sees. [6] and [7] de- 
scribe SpartyJet's input and output facilities. Finally, Sec. [8] describes the 
capabilities of SpartyJet's graphical interface. 

2 A simple example 

The simplest way to get a feel for how SpartyJet works is to consider an exam- 
ple; in this section we walk through the script examples_py/ simpleExample . py. 
This script runs the anti-fcx algorithm on the first 10 events listed in data/ Jl_Clusters . dat, 
makes a simple measurement on the found jets, and stores the results. 

• Load the libraries that are needed for the algorithms that you are run- 
ning (you need to source setup . sh in the main directory first to set up 
environment variables) : 

from spartyjet import * 

• Create a JetBuilder object to manage SpartyJet analyses. The argu- 
ment sets the output message level — options are {DEBUG , INFO, WARNING, 
ERROR}. Log messages throughout the code are tagged with a message 
level; messages with level lower than the current output level are sup- 
pressed. Note that the SpartyJet namespace is aliased as SJ. 
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builder 



= SJ . JetBuilder CSJ . INFO) 



• Create an input object with the name of the file containing the events, 
using the getlnputMaker helper function. This function guesses the type 
of input file based on the file extension. Many types of input are available; 
see Section [6] 

input = get Input Maker C '../ data/ J l_Clust ers . dat ' ) 
builder . configure_input C input) 



• Define the jet analyses that you want to run. Most analyses begin with 
a jet algorithm, implemented in FastJet via the Fast JetFinder tool. 



See Section for 5.1 for more options. Note that the fast jet namespace is 
aliased as f j . 

name = 'AntiKt4' 

alg = f j . ant ikt _ algorithm 

R = 0.4 

antikt4Finder = SJ . Fast Jet . Fast JetFinder (name , alg, R) 
analysis = S J . Je t Analys i s C ant ikt 4Finder ) 



• Pass analysis to your JetBuilder. A sequence of jet tools defines a jet 
analysis. A jet finder is one example of a JetTool; see Section[5]for many 
more. 

builder . add_analysis (analysis) 



• Insert another tool in the chain, in this case making a measurement of 
jets' angular moments in rj and (p. These will also be stored in the output 
ROOT file. add_jetTool() can take a second argument, the name of an 
algorithm to add the tool to; otherwise the tool is added to all algorithms. 
Tools can also be added directly to analyses via JetAnalysis : : add_tool() 

builder. add_jetTool(SJ.EtaPhiMomentToolO) 

• Configure (optional) simple text output for quick visual check of results. 

builder . add_text_output C ' . . /data/output/text_simple . dat ' ) 



• Configure the Ntuple output by specifying the name of the tree and the 
ROOT file you want the data to be stored in. This output can be ma- 
nipulated via your own ROOT scripts or be viewed with the SpartyJet 
GUI. 

builder . configure_output ( ' SpartyJet_Tree ' , ' . . /data/ output/ simple . root ' ) 

• Give the command to run the algorithms on the first 10 events 

builder . process_events (10) 



Running the script will process the first 10 events on the file specified in 
the input object and produce the .root file specified in conf igure_output. To 
view the output with the GUI, run 
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sparty data/output/simple . root 

(spartyjet/bin must be in your $PATH.) This is meant as a basic introduction, 
and there are many more functions than listed here. See the other examples for 
more. 

3 Installation 

3.1 Requirements 

SpartyJet should build and run on any Unix-like operating system, including 
Mac OS X. A Cygwin build is presumably possible but not tested. The standard 
build system is via Makefiles; there is also a CMake build system which requires 
CMake. SpartyJet uses ROOT extensively for input, output, and Python 
wrapping via PyROOT. SpartyJet 4.0 has been tested with versions 5.30 and 
5.32, but older versions may be OK. To use the Python interface to Sparty- 
Jet you must have built ROOT with PyROOT enabled. We have tested with 
Python versions 2.6 and 2.7. SpartyJet now makes heavy use of recent Fast- 
Jet features, so FastJet version 3.0+ is required. If you do not already have 
FastJet installed, SpartyJet can build an internal version. If you want to 
use the StdHEP input facility, you will need a Fortran compiler; we've tested 
with gfortran. 

3.2 Compilation 

To compile: 

# Set up ROOT such that root-config is in your path 

# for example source root/bin/thisroot . sh 
cd spartyjet 

source setup. sh 
make 

If you do not already have FastJet installed, do make f ast j et and source setup . sh 
(again) before make. This builds FastJet inside SpartyJet and sets the rele- 
vant environment variables. 

SpartyJet has several building options to note: 

• FastJet: SpartyJet depends on FastJet for jet finding and some inter- 
nal features, and the latest version is included in the SpartyJet distribu- 
tion. If you prefer to use your own installation, simply add your-f ast j et/bin 
to the environmental variable $PATH such that f astjet-conf ig can be 
found. 

NOTE: If you have linking problems between your version of FastJet 
and SpartyJet, either recompile your FastJet with the — with-pic 
option enabled before compilation, or have SpartyJet compile its own 
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version. Note also that to enable all FastJet plugins, you must pass the 
— enable-allcxxplugins flag to configure. This is done by default for 
the built-in version. 

• StdHEP libraries: These require a Fortran compiler and are automat- 
ically compiled if you have gf ortran, f 77, or g77 in your $PATH. If you 
would like to try a different compiler, set the environmental variable $F77 
to the compiler binary. 

• Pythia 6/8 interface: If you have ROOT compiled with the Pythia 6 
and/or Pythia 8 interfaces enabled, you can use this from within Sparty- 
Jet to generate events in Pythia and feed the output directly to Sparty- 
Jet. To enable this, set the variable $PYTHIA6DIR and/or $PYTHIA8DIR. 
If you do not have PYTHIA support in ROOT, you can add it by doing: 
cd $R00TSYS 

./configure — enable-pythia6 — enable-pythia8 

— with-pythia6-libdir=/my/pythia6/ 

— with-pythia8-incdir=/my/pythia8145/ include/ 

— with-pythia8-libdir=/my/pythia8145/lib/ 

make 

Building SpartyJet creates a set of libraries in spartyjet/lib that you 
can load from a ROOT session or Python script, or you can link to to build an 
executable. 

libs/libExternal.so - Fast Jet and other code SpartyJet depends on 

libs/libJetCore.so - Core infrastructure 

libs/liblO.so - Facilities for reading and writing a variety of file formats 

libs/libFastJet.so - Tools that rely on FastJet, including jet finding 

libs/lib JetTools.so - Other Jet Tools 

libs/libEventShape.so - Thrust and other event shapes 
libs/libSpartyDisplay.so - SpartyJet GUI 

libs/libExternalTools.so - A set of third-party jet tools, with wrappers 
3.3 Running 

Working examples of how to use SpartyJet can be found in the following 
directories: 

spartyjet/examples_py : Python scripts (recommended) 
spartyjet/examples_C : Compiled programs in C++ 

The Python interface to SpartyJet is strongly preferred, and C++ ac- 
cess may be deprecated in a future release. To use the Python scripts, some 
environment variables needs to be set, which can be accomplished via: 

source setup. sh 

in the spartyj et/ directory. This exports the relevant paths to your LD -LIBRARY _PATH 
and sets the environment variable SPARTYJETDIR, which allows the SpartyJet 
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Python modules and libraries to be accessible from any directory The relevant 
lines of setup. sh could also be copied into your shell's rc file, e.g. "/.basrirc. 
You will also need ${R00TSYS}/lib in your $PYTHONPATH. (This is necessary to 
use PyROOT.) 

3.4 CMake build 

SpartyJet now includes a CMake build system. If you have CMake installed, 
you can build SpartyJet by creating a build directory (e.g., spartyjet/build) 
and running: 

cmake . . 
make 

If you are using the built-in Fast Jet distribution, you need to run: 

cmake . . 
make fast jet 
cmake . . 
make 

To set environment variables correctly, you may need to run source setup . sh 
in the main directory before running SpartyJet programs. In a future release, 
the CMake build system should allow natively building on Windows (not Cyg- 
win), but this will likely require Windows builds for Sparty Jet's dependencies. 

CMake can generate project files for your IDE of choice, e.g., to build an 
Xcode project just do 

cmake . . -G Xcode 

4 JetBuilder 

JetBuilder is the job manager for SpartyJet. JetBuilder takes the input 
from an InputMaker (see Section[6]) and passes it through a set of JetAnalyses. 
A JetAnalysis is made up of a sequence of JetTools. The final list of jets, and 
associated moments, is passed to an NtupleMaker, which prepares the output. 
This is shown schematically in Fig. [TJ 

4.1 Input Functions 

Example: examples_py/ inputExample . py 
Input is passed to JetBuilder via: 

builder . conf igure_ input (input , save Input =True ) 

where input can be any class deriving from InputMaker. See Section [6] for 
examples. The savelnput flag, true by default, determines whether to save the 
input particles in the output file. Saving input particles is needed for most event 
displays but not for plotting run variables (jet mass, moments, etc.). 
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Figure 1: The structure of a SpartyJet analysis. A JetBuilder gets input 
from a file using an InputMaker, passes the input through a sequence of input 
JetTools, and passes the output to several JetAnalyses (labeled JetAlgorithms 
in this diagram). JetAnalyses consist of a sequence of JetTools that are run 
sequentially. The output of each JetAnalysis is passed to an NTupleMaker 
which stores the final jets and accompanying moments in a file. 
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4.2 JetAnalysis Options 



JetAnalyses are blocks of code that act on a set of Jets — implemented as a 
JetCollection. A set of JetTools forms a JetAnalysis, and a JetBuilder 
holds a set of JetAnalyses that are each run on its inputs. Examples of specific 
tools can be found in Sec. [5] 

JetAnalyses can be added to a run via: 

builder . add_analysis (analyis) 

Alternatively, analyses can be set up implicitly by just passing the JetBuilder 
a JetTool: 

builder . add_default_analysis (tool) 

where tool is typically a jet finder, which forms the basis of the tool chain. 
Default tools are added before and after — currently just negative energy cor- 
rectors, if this option is enabled (it is not by default). To enable negative energy 
correction, call 

builder . do_correct_neg_energy (True) 

This flips the sign of the energy of any negative-energy input particles, then 
after jet finding adjusts jets' energies accordingly. 

JetTools can be added directly to analyses, or through the JetBuilder: 

# add a tool a specific analysis 
analysis . add_tool (tool) 

# add a tool to all analyses registered with builder 
builder . add_jetTool (tool) 

# add a tool to a specific analysis via builder 
builder . add_j etTool (tool , ' AnalysisName ' ) 

Tools can be added to the front of the sequence with: 

analysis . add_tool_front (tool) 

# or 

builder . add_jetTool_front (tool) 

Analyses are passed to the JetBuilder as pointers, so tools can be added 
to them at any time before calling JetBuilder: :process_events(). 

A single sequence of JetTools is run on the input particles before they are 
passed to each JetAnalysis. This sequence starts empty; to add to it use: 

builder . add_jetTool_input (tool) 

This is useful for initial tools like 77 cuts or detector simulation that are common 
to all algorithms. 

4.3 Output options 

SpartyJet by default retains information about each jet's constituents. JetBuilder : : add_analysis ( ) 
and JetBuilder: : add_default .analysis () each take a second bool argument 
that determines whether to save constituent information for each jet: 

builder . add_analysis (analysis , withlndex =True ) 
builder . add_default_analysis (tool , with!ndex=True) 
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The default is True. For this to be useful in the output, the input should be 
set up to store input particles in the output file as well. The full recombination 
history is stored in memory, but storage to disk has not yet been implemented. 
We hope to have this available in a future release. 

A third option can be passed to JetBuilder: : adcLanalysis () , which if 
True tells the builder to only save jet and event moments, not jet variables like 
rj, pr, etc. This can be useful to save space, or if only event-shape tools are used. 
In fact, JetBuilder has a method add_eventshape_analysis (analysis) that 
is simply an alias to add_analysis (analysis , False, True). 

A text file output option tells JetBuilder to produce an easily-readable text 
file that contains a list of all jets found from all algorithms for all events. To 
turn on the text file output, you must call builder . add_text_output () , and 
pass it the filename you want to create. For example: 

builder . add_text_output C ' . . /data/ output/ text_output . dat ' ) 

The main output of SpartyJet is a ROOT file holding input particles, jet 
momenta, and jet and event moments. The format of this file as well as some 
additional JetBuilder options controlling it, are described in Sec. [7] 

4.4 Minimum Bias Overlay 

Example: examples_py/ overlayExample . py 

JetBuilder allows the user to add minimum bias (MB) events to the signal 
events to study the effects of pileup. To enable MB events, one must: 

1. Create another input object: 

MBinput = SJ . StdTextlnput ( ' . . /data/MB_Clusters . dat > ) 

2. Tell JetBuilder to add n MB events to each signal event: 

builder . add_minbias_events (n , MBinput, po i s s on=False ) 

JetBuilder will start at the beginning of the MB data file and read the first 
n events for the first data event, then the second n events for the second data 
event, so on. When the end of the MB file is found, it will simply continue from 
the beginning. If the third, optional, argument is True, the JetBuilder will 
draw the number of MB events from a Poisson distribution (default is False). 
In this case, n is the Poisson mean or expected number of MB events. 

4.5 Options controlling screen output 

SpartyJet can be configured to produce screen output at varying levels of 
verbosity. The most important point of control is the global message level, which 
can be one of {DEBUG, INFO, WARNING, ERROR}. Each message produced in 
the course has an associated level, and will be printed to the screen if its level is 
at least as high as the global level: e.g., if the global level is WARNING, WARNING 
and ERROR messages will be printed. The global message level can be set in the 
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JetBuilder constructor, or later via the JetBuilder: : set_message_level () 
method: 



builder = SJ . JetBuilder (SJ . INFO) 

# or 

builder . set_message_level (SJ . WARNING) 

# equivalent to set _me s s age_l eve 1 C S J . ERROR) : 
builder . silent_mode () 

SpartyJet will report on the progress of the run by printing "Processed 
Event: N" lines, by default every event. You can change the frequency via: 

# prints every 100 events 
builder . print _event_every (100) 

4.6 Running 

Once all analyses have been set up and all options loaded, it's time to run. To 
run over all events in the input, simply do 

builder . process_events () 

You can also specify how many events to process, and what event number to 
begin at: 

# process 100 events , starting at the 250th 
builder . proce s s_e vent s ( 100 , 250) 

# alias to pro c e s s _e vent s ( 1 , N): 
builder . process_one_event (N) 

5 JetTools 

JetTools are blocks of code that act on a JetCollection for every event. They 
generally perform one or more of the following functions: 

• Find jets 

• Add or remove jets from the list. 

• Modify the jets themselves. 

• Add information about each jet as a JetMoment. 

• Add information about each event as an EventMoment. 

Jet tools can be added either before or after the primary jet finder (e.g., the 
fcx algorithm) in the JetAnalysis. This section describes the set of JetTools 
shipped with SpartyJet. The relevant definitions can be found in JetTools/ 
(core SpartyJet tools), Fast JetTools (wrappers around FastJet tools), and 
ExternalTools (FASTjET-based tools provided by third parties). 

SpartyJet and FastJet have evolved alongside each other, and many fea- 
tures formerly implemented natively in SpartyJet are now outsourced to Fast- 
Jet algorithms or tools. We have endeavored to keep pace, but realize there is 
still some duplication, especially with the suite of tools available in FastJet 3.0. 
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Where available, FASTjET-based tools are the preferred means of performing jet 
finding (fastjet: : ClusterSequence), selection (fastjet: :Selector), manip- 
ulation (fastjet: : Transformer), and measurement (fastjet: : FunctionOf PseudoJet). 
The improved wrapping of Fast Jet code in SpartyJet 4.0 should enable es- 
sentially any FastJet tool to be used within SpartyJet. We expect that fu- 
ture development of jet tools will be done within the context of FastJet, with 
development in SpartyJet focused on the Python interface, I/O facilities, and 
graphical interaction. 

As noted in [4], the planned future development of FastJet includes a 
"contrib" project of externally written code. We envision that many external 
tools currently provided with SpartyJet will migrate to this space when it 
becomes available. In the meantime, see ExternalTools/README for details on 
the origins and authorship of the tools in that directory. To add your own 
tools to SpartyJet, you will need to cither create a shared library that a) 
links against compiled C++ code or b) is loaded by ROOT. See the comments 
in UserPlugins/Makef ile for more information on creating such a library, or 
including your own code in SpartyJet's build. UserPlugins/ExamplePlugin 
gives an example. 

Note: In this section we sometimes switch from Python to C++ syntax for 
clarity of argument types. 

5.1 Jet finders 

All jet finding is done via FastJet jet algorithms. The basic wrapper is de- 
fined in Fast JetTools/Fast JetFinder .hh. There are two basic operations: jet 
finding, and reclustering. 

Fast JetFinder: Finds jets using FastJet algorithms. It has two constructors: 

Fast JetFinder C string name, f ast j et :: Jet Algorithm alg , double R=0.4, 
bool area=false) 

Fas t Je t F inder C f ast j e t : : Jet Def init i on , string name, bool area=false) 

The second form allows you to pass your own fastjet : : JetDef inition, 
including a plugin algorithm; see FJExample .py for examples. By default, 
a Fast JetFinder finds inclusive jets with px > 5 GeV. This can be mod- 
ified via set_ptmin (double) , set_dcut (double) , and set_njets(int). 

The last two correspond to exclusive jet finding; note that dcut has di- 
mension GeV 2 . Setting any of these overrides the others. 

Fast JetRecluster: Similar to Fast JetFinder, but uses a given jet algorithm 
to recluster the constituents of each jet in an event. Has two constructors, 
with the same arguments as Fast JetFinder. 

The full set of default algorithms from FastJet is available. To use the in- 
cluded but optional plugin algorithms, uncomment the relevant lines in External/ExternalLinkDef .hpp 
and recompile SpartyJet. 

Two additional plugin algorithms are available in the ExternalTools direc- 
tory: 
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NjettinessPlugin: Finds jets by minimizing the iV-jettiness measure [H [B] 
over the event with a fixed number (N) of axes. 

QjetsPlugin: Implements the "Qjets" algorithm of [?]• 

5.2 Selectors 

These tools allow the user to remove some Jets from an input /output JetCollec- 
tion. Most selectors can now be formed with the standard Fast Jet Selectors 
via the SelectorTool class: 

selector = f j . SelectorPtMin (200 . 0) * f j . SelectorNHardest (2) 

See the Fast Jet manual or fast jet-install/include/fast jet/Selector .hh 
for the full set of available selectors. The compound assignment operators &= 
and I = are supported, as well as (via some duck punching in the SpartyJet 
Python wrapper) the binary operations *, &&, and I I. Note that (si * s2) 
applies s2, then si; (si && s2) applies both separately. The result is the same 
iff the selectors commute. 

Many native SpartyJet selectors are defined in JetTools/JetSelectorTool . hh; 
the ones that do not duplicate a Fast Jet selector (and are thus not deprecated) 
are: 

JetInputPdgIdSelectorTool(std: :vector<int> pdglds): Removes input 
"jets" with given PDG IDs. (Useful when the input jets are just single 
particles from a Monte Carlo where leptons, neutrinos, etc. are included.) 
The input file must have included PDG IDs. 

JetMomentSelectorTool<T>(std: : string momentName, T min, T max): Finds 
the given jet moment (calculated by another tool) and requires it be within 
(min, max). T can be any type supporting less-than comparison. 

5.3 Transformers 

Fast Jet 3.0 provides a common base class for jet manipulation: fast jet : : Transformer. 
Transformers can remove particles (e.g., filtering), re-arrange substructure, or 
tag/reject jets. To add a given transformer to an analysis, use the Transf ormerTool: 

Trimmed = S J . Jet Analy s i s C [ . . . some jet finder ...]) 

trimmer = f j . Filter (0 . 35 , f j . Sele ct orPt Fr act ionMin ( . 03) ) 

Tr immed . add_tool (SJ . FastJet . TransformerTool ( "TrimmerTool " , t r immer ) ) 

In C++ code any class deriving from fast jet :: Transformer is accept- 
able; in Python a ROOT dictionary must be generated. See the comments in 
UserPlugins/Makef ile for more information on including your own classes in 
SpartyJet. The currently available set of Transf ormers is: 

FastJet native: 

Boost: Boost a jet to the rest frame of a reference jet. 

CASubJetTagger: Versatile and generic substructure identification for Cam- 
bridge/Aachen jets. 
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Filter: Recluster a jet with a smaller R and only keep subjets passing a given 
criterion [5]. 

GridMedianBackgroundEstimator: Two different ways of estimating back- 
ground radiation. 

JetMedianBackgroundEstimator 

Mas sDropT agger: Tagger that peels off soft radiation until a splitting is found 
where the two parents have significantly less mass than the child [5]. 

RestFrameNSubjettinessTagger: Implements the rest-frame version of the 
./V-subjettiness jet shape [5]. 

Subtractor: Subtracts estimated background energy. 

JHTopTagger: The Johns Hopkins top tagger 10 . 

Unboost: Unboost a jet from the rest frame of a reference jet. 

Pruner: Rebuilds a jet with a new cluster sequence, vetoing soft, large-angle 
mergings [TT1 IT2] . 

External tools included with SpartyJet: 

HEPTopTagger: An implementation of the HEPTopTagger of [131 E], provided 
by the authors. 

CMSTopTagger: An implementation of the "CMS" top tagger [13 [16], written 
by one of the SpartyJet authors, based on JHTopTagger. 

TopTaggerDipolarityTool: Adds dipolarity [17 to any top tagger, running 
the tagger, then storing the dipolarity measured on its substructure. 

The Fast jET-native transformers are described further in the Fast Jet doc- 
umentation. Examples of using many of these transformers can be found in 
examples_py/FJToolExample .py and examples_py/Boost2011 .py. 



5.4 Jet and event moment tools 

These tools calculate moments for each jet or event, which can be any type 
that ROOT knows how to store, most commonly doubles or ints. The generic 
JetMomentTool and EventMomentTool calculate and store any user-implemented 
JetMoment<T> or EventMoment<T> object. See JetTools/ JetMomentTool. hh 
for some specific examples, and FJToolExample .py for moment tools in action. 

The Fast Jet 3 base class FunctionOf PseudoJet<T> provides a common in- 
terface for jet measurements. This is wrapped in SpartyJet by the Pseudo JetMomentTool<T> 
class. The template argument T gives the type of the function output. 

# An example of using a Funct i onOf Ps eudo Jet measurement 

nsub3 = f j . Nsub j ett iness C3 , Nj ettiness . onepass_kt_axes , 1.0, 1.0) 

Ant iKt 10 . add_tool (SJ . Fast Jet . Pseudo Jet Moment Tool (double) (nsub3 , " tau3 " ) ) 
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Most jet and event moments in SpartyJet are of type Double32_t. This is 
a ROOT-dcfined type that behaves like a double in memory but is stored as 
float; we feel this is a reasonable compromise between precision mid-calculation 
and saving storage space. In the Python package RDDT.Double32_t is imported 
as simply double, as in the above example. 

The following FunctionOf PseudoJets are available, all defined in spartyjet/ExternalTools. 
Examples of their use can be found in examples_py/Boost2011 .py. 

MinMassFunction: Finds three exclusive subjets, then measures the smallest 
invariant mass between any two, as in the CMS top tagger [T3I ITS] , 

zCellFunction: Measures the z ce n variable of the "Thaler and Wang" top 
tagger [TB] , 

zCutFunction: Measures the z* ut of the ATLAS top tagger [T§] , 
Nsubjettiness: Measures the version of iV-subjettiness described in [5U] , 

The following are other moment-storing tools available. They may be phased 
out in favor of more explicitly FASTjET-based versions. 

HullMomentTool: This tool finds the convex hull enclosing each jet and saves 
the hull length and area as Hull and HullA respectively. 

EtaPhiMomentTool: This tool calculates angular second moments in rj and <j> 
of each jet stores them as M2eta and M2phi. 

PtDensityTool: This tool calculates each event's pr density using FastJet. 
It does this by finding all the jets in the event with no minimum px 
requirement. It then extracts the px density from these jets by selecting 
the mean px density for each bin in rj. These pt densities are stored as 
ptDensity and the rj bin limits are stored as ptDensityBins. 

JetAreaCorrectionTool: This tool uses the area of each jet and the pTDen- 
sity found by the PtDensityTool to calculate a correction (stored as jet 
moment JetAreaCorr) to the jet's px- 

YSplitterTool: This tool uses FastJet to calculate the y values associated 
with a set of recombinations. In this implementation, SpartyJet will run 
a FastJet algorithm of the user's choice on the constituents of a given 
jet. It can be called with either of the following constructors: 

YSpl i t t er Tool ( f loat R, f as t j et :: Jet Algorithm alg , int ny , int njet) 
YSpl i t t erTool C f ast j e t : : JetDef init i on *jet_def, int ny , int njet) 

where njet is the number of jets for which the y values will be calculated 
and ny is the number of y values to calculate for each jet. 



14 



5.5 Miscellaneous tools 



ForkToolParent and ForkToolChild: This pair of tools allows the forking of 
JetTool chains. ForkToolParent merely saves a copy of its input. A 
ForkToolChild is associated with a specific parent, and it reads in the 
JetCollection saved by its parent. This allows, for example, one jet 
algorithm to be run combined with several different jet-modifying tool 
chains for comparison. See FJToolExample .py for a usage example. 

CalorimeterSimTool: This tool applies a very simple calorimeter simulation 
to its input jets. Inputs are sorted into calorimeter cells on a specified rj-(j) 
grid. For each non-empty cell, a massless output particle is created with 
the direction of the cell and the total energy of all particles in the cell. 

RadialSmearingTool: This tool wraps Peter Loch's DetectorModel code for 
calorimeter simulation. For more information, see Peter's website. A 
usage example is given in Boost2011 .py. 

JetNegEnergyTool: This tool is meant to be run twice: once before jet finding 
and once afterward. On first run, the tool finds and stores all input par- 
ticles with negative energy. For each such particle it inverts the energy to 
be positive. On second run, the JetNegEnergyTool loops over jets, and 
for each constituent that initially had a negative energy, it corrects the 
jet energy by subtracting twice the constituent's (positive) energy. The 
JetBuilder method do_correct_neg_energy (true) inserts this pair of 
tools before and after all jet finders added with add_def ault_analysis (tool) ; 
by default this is not done. 

EConversionTool: This tool simply converts the units of all the jets between 
MeV and GeV. The user can convert to arbitrary units as well. 

HardProcessMatchTool: Assuming the input file includes information about 
the hard scattering (this is true of HepMC files, e.g.), finds the closest 
hard parton for each jet and stores the AR distance as a jet moment. 

AngularCorrelationTool: Measures the angular correlation functions de- 
scribed in [21] . storing R n and m n for each peak found up to three as 
jet moments. 

QjetsTool: Runs the "Qjets" plugin algorithm repeatedly on each jet, storing 
the average pruned jet mass and its "volatility", as described in [7]. 

WTaggerTool: This tool wraps the VF-tagging method of [32], which includes 
a large number of substructure and mass cuts. The cuts are taken from 
data files in external/wtag-1 . 00/data. So far there is no way to re-train 
the cuts from within SpartyJet — the idea is to take a pre-trained W- 
tagging method and plug it into a SpartyJet analysis. Since the tagger 
is taken "out-of-the-box" , there are no input parameters: 

WTaggerTool () 
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6 Input 



All SpartyJet jobs need an InputMaker object to read input from some data 
file and prepare a list of four-vectors for JetAnalyses to process. There are 
several types of InputMakers available. An example of the implementation 
for each type of input can be seen in examples_py/inputExample .py. For 

Python scripts, the top-level module python/ sparty jet/ init .py defines 

the helper function getlnputMaker (f ileName) which will create the appropri- 
ate InputMaker by looking at the filename extension. 

6.1 NtuplelnputMaker 

Sample: data/ J2_clusters . root 

This form of input reads ROOT files. This InputMaker requires the com- 
ponents of the input 4-vectors to be stored in separate branches of a ROOT 
TTree. The following definitions are supported: 

• px, py, pz, E 

• (psuedo) rapidity, phi, pt, E 

• (psuedo) rapidity, phi, pt, m 

You need only specify how the information is stored (array or vector / float or 
double) and the names of the branches. 

As an example, to set up an NtuplelnputMaker to read the file data/ J2_clusters . root, 
if you don't know how variables are internally stored in your ntuple, do the fol- 
lowing: 

root -1 data/ J2_clusters. root 

root [0] clusterTree->MakeClass("test") ; 

Open the file test.h and check to see how the variables are stored. In this 
example, we see lines like: 

vector <float > *Cluster_eta ; 

indicating that our 4-vectors are stored in vectors of floats. Now to configure 
SpartyJet to accept this, we need to: 

• Create an NtuplelnputMaker of the correct type: (in our case: vector<f loat> 
for (eta, phi, pt , E)). 

input = SJ . NtuplelnputMaker CSJ . NtuplelnputMaker . EtaPhiPtE_vector_float) 

For full list of Input codes see: JetCore/InputMaker_Ntuple .hh 

• Configure the names of the TBranches 

input . set_pref ix ( ' Cluster, ' ) 
input . set_n_name ( ' N ' ) 

input . set_variables ( 'eta 1 , 'phi ' , ' p_T ' , ' e ' ) 

input. setFileTreeC' . . /data/ J2_clusters . root ' , ' clusterTree J ) 
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• Specify if input is massless, only useable in eta,phi,pt,E mode (if true, 
pt is ignored): 

input . set_masslessMode (True) 

• Set the input file and tree names: 

input. setFileTreet' . . /data/ J2_clusters. root ' , 'clusterTree') 

Python Shortcut: 

To allow SpartyJet to configure your Ntuple using some assumptions use 
the following helper function: 

input = createKtuplelnputMaker C ' .. /data/ J2_clusters . root ' , input pref ix = ' 
Cluster ' ) 

Delpheslnput 

DelphesInputMaker is a minor extension of NTuplelnputMaker that reads the 
ROOT files produced by the detector simulator Delphes. Only calorimeter 
cells are read in. 

6.2 StdTextlnput 

Sample: data/Jl_Clusters . dat 

This form of input reads ASCII files. To separate events, put one of the 
following lines between the events: 

. Event 
. event 
N 
n 

(only the .E or .e is important in the first two). 
The form of the four vectors should be: 

E px py pz 

This input is configured simply with: 

input = SJ.StdTextInput('../data/Jl_Clusters.dat') 

If the form is the opposite (px py pz E), then call the function 

input . invert_input_order (True) 

and it will be read in properly. 

An example of this input can be seen in data/Jl_Clusters . dat 
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6.3 StdHepInput 

Sample: data/ttbar_smallrun_pythia_events .hep 

This form of input reads StdHEP format XDR files. It will look for particles 
with the status code of 1 (final state). It is also able extract the PDG ID code 
for each particle from the input data to allow further filtering and matching. 
Access to intermediate particles such as the participants in the hard scattering, 
or B hadrons from b quark decays, should be possible in the near future. 

This input is configured simply with: 

S3 . StdHepInput C ' . . / data/ ttbar_smallrun_pythia_events . hep ' ) 

NOTE: To read StdHep files, you must enable StdHep compilation as ex- 
plained in Section [3} 

6.4 CalchepPartonTextlnput 

Sample: data/gg_ggg_events . dat 

This form of input reads output from CalcHEP. It reads in the number of ini- 
tial and final state particles, and then for each event saves only the information 
for the final state particles. 

This input is configured simply with: 

SJ . CalchepPartonTextlnput C ' . . /data/ gg_ggg_events . dat ' ) 

6.5 HepMCInput 

Sample: data/Zprime_ttbar .hepmc 

This form of input reads HepMC (version 2) format ASCII files. This class 
reads in the four-vectors and PDG IDs of the particles denoted with a status 
code of 1 (not decayed, final state). 

6.6 Pythialnput 

This form of input generates and reads events directly from Pythia, without 
ever having to write them to a file. This requires ROOT's Pythia interface; 
versions 6 and 8 will both work. See examples_py/pythiaExample .py for an 
example of using Pythia in this way. 

6.7 FourVecInput 

A FourVecInput takes four- vectors from some other code; the input class is 
templated on a "Reader" class that must provide a simple interface for retriev- 
ing four- vectors. See IO/FourVecInput .hh for a complete specification, and 
examples_C/FourVecExample . cc for an example. This does not currently work 
in Python, since you would have to generate a dictionary for FourVecInput <YourReaderClass>. 



18 



6.8 Input Options 
Multiple input files 

The Mult i Input class can be used to string a set of input files together. See 
examples_py/mergedInputExample .py for an example. For ROOT files, the 
current implementation opens all input files before beginning, which may be 
inefficient. Other files are opened sequentially. 

Rejecting bad input 

The InputMaker can be set to remove four-vectors with negative energy and 
non-physical momenta by using the following function. 

input . reject_bad_input (False) 

The current default is False; no checks will be done. (An alternative to this 
method of dealing with bad input is to use the JetNegEnergyTool, described 
in Sec. [§) 

Reading of PDG ID codes 

The InputMaker can be set to read PDG ID codes from the input data with 
the following function. This is done by default. 

input. readPdgld(True) 

This makes the PDG IDs available for input selection and saves the IDs of the 
input particles for offline analysis. 

7 Output 

After a SpartyJet run, the result is a ROOT TTree containing jet variables 
for each algorithm added, plus variables for input particles to the jet algorithms. 
Jet and event moments are also stored. 

The output ROOT file contains a TTree (the file and TTree name are 
set via builder . conf igure_output (treename , filename). The TTree con- 
tains a branch for each jet variable, named by default {AnalysisName_eta, 
AnalysisName_phi, AnalysisName_e, AnalysisName_mass, AnalysisName_pt 
}. (For this reason it is important that each analysis have a unique name!) If 
input particles are being stored, there are similar branches for the input parti- 
cles. Every jet moment has an associated name and is stored in a branch named 
AnalysisName jmomentName. For each analysis, an integer variable AnalysisNameJJ 
is stored, giving the number of jets for each event. 

7.1 Output variable type 

It is possible to choose the type of the variable saved in the TTree. The choices 
are C array vs. STL vector, and floats vs. doubles. 
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# can also do SJ.kArray and SJ.kDouble 

builder . set_output_type CSJ . kVector , SJ.kFloat) # (default) 

This affects the jet momentum variables, but not jet or event moments. Jet 
moments are always stored as vector<T> where T was the template parameter 
to the jet moment (the type that the moment returned. Event moments are 
simply stored as bare Ts. 

7.2 Constituents 

For all analyses, constituent information is saved as follows, assuming that the 
analysis was added to the JetBuilder with option withIndex=True (this is the 
default). Assuming an analysis named My Jet has been added, two additional 
variables are stored in the ROOT TTree: 

MyJet_numC 

MyJet_ind 

MyJet_numC is an array of size MyJet_N. MyJet_numC [i] is the number of 
constituents of i thjet. MyJet_ind is an array of size InputJetJJ. MyJet_ind[i] 
is the index of the jet to which the i th input constituent has been assigned. 

For example: 

myTree . Draw( ' Input Jet_e ' , ' AntiKtlO_ind==0 ' ) 

will give the energy distribution of constituents in jet number (i.e. highest pt 
jets) for the AntiKtlO collection. 

8 Graphical interface 

SpartyJet output ROOT files can be explored with a graphical interface, 
launchable by running 

$> sparty foo.root [bar. root ...] 

(spartyjet/bin must be in your $PATH.) A screenshot of the GUI in action 
is shown in Fig. [2j The user can select which algorithms to view by ticking 
the boxes under "JetCollections" . On the left are several event- by- event views, 
which will be drawn separately for each algorithm. The number of rows and 
columns are set in the upper left. 

Additional analyses can be run (event-by-event) on the fly using the menu in 
the lower left. These are based on a new "live algorithm" facility in the Sparty- 
Jet Python package, which extends certain common analyses with knowledge 
of their input parameters so the GUI can build them live with user-provided 
parameters. These analyses can be run on the inputs from any file loaded on 
launch. In particular, you can launch the GUI with one or more ROOT files 
with no analyses run at all, only inputs. On-the-fly analyses provide a sim- 
ple and powerful way to explore jet analysis dynamics, and we hope to extend 
these capabilities in future releases. High on our wish list is event generator 
integration, which would make the GUI self-contained. 
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On the right side of the control panel, full-run plots can be selected, which 
are plotted for all algorithms together (an example of this output is shown in 
Fig. [3]) . Check boxes are provided for the standard four-momentum variables, 
but any stored jet moment can also be plotted by entering the name in the 
box below, e.g. $$_tau3/$$_tau2 to plot the ratio of 3- to 2-subjettiness if the 
Nsubjettiness moment has been measured as in Boost2011 .py. Note that $$ 
is a placeholder for the analysis name, and the syntax is that of TTree : : Draw. 
Moments found in the input files are also given in the box below the jet variables, 
but note that not all moments are stored for all analyses! 

Cuts can be added using TCut syntax, e.g. AntiKtlO_mass > 150 && AntiK10_mass < 
Finally, legend labels for each algorithm can be given; the syntax is ROOT 
TLatex text, e.g. #phi_{0} produces <f)Q. Several drawing options are provided 
below the Draw button. Finer control can be gained by opening the ROOT 
histogram editor in the output canvas. 
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Figure 2: A screenshot of the SpartyJet graphical interface. 
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Figure 3: An example canvas produced by the run plot option (above), with the 
options that produced it (below). 
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Contact information 



SpartyJet website: |http : //projects .hepforge . org/spartyjet 



Any questions/comments/suggestions, email: 

Pierre- Antoine Delsart: delsart@in2p3.fr 
Joey Huston: huston@ pa.msu.edu 

Brian Martin: marti347@ msu.edu 

Chris Vermilion: verm@ uw.edu 
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